home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / Translation.a < prev    next >
Encoding:
Text File  |  1996-05-01  |  12.0 KB  |  349 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        Translation.a
  3. ;
  4. ;    Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5. ;
  6. ;    Version:    Technology:    Macintosh Easy Open 1.1
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__TRANSLATION__') = 'UNDEFINED' THEN
  19. __TRANSLATION__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  25.     include 'Files.a'
  26.     ENDIF
  27.     IF &TYPE('__COMPONENTS__') = 'UNDEFINED' THEN
  28.     include 'Components.a'
  29.     ENDIF
  30.     IF &TYPE('__TRANSLATIONEXTENSIONS__') = 'UNDEFINED' THEN
  31.     include 'TranslationExtensions.a'
  32.     ENDIF
  33. ;  enumerated types on how a document can be opened
  34. ; typedef short                         DocOpenMethod
  35.  
  36.  
  37. domCannot                        EQU        0
  38. domNative                        EQU        1
  39. domTranslateFirst                EQU        2
  40. domWildcard                        EQU        3
  41. ;  0L terminated array of OSTypes, or FileTypes
  42. TypesBlock                RECORD 0
  43. elements                 ds.l    64
  44. sizeof                     EQU *                    ; size:   $100 (256)
  45.                         ENDR
  46.  
  47.  
  48. ; typedef OSType *                        TypesBlockPtr
  49.  
  50. ;  Progress dialog resource ID
  51.  
  52. kTranslationScrapProgressDialogID EQU    -16555
  53. ;  block of data that describes how to translate
  54. FileTranslationSpec        RECORD 0
  55. componentSignature         ds.l    1                ; offset: $0 (0)
  56. translationSystemInfo     ds.l    1                ; offset: $4 (4)
  57. src                         ds        FileTypeSpec    ; offset: $8 (8)
  58. dst                         ds        FileTypeSpec    ; offset: $1C (28)
  59. sizeof                     EQU *                    ; size:   $30 (48)
  60.                         ENDR
  61. ; typedef struct FileTranslationSpec *    FileTranslationSpecArrayPtr
  62.  
  63.     IF FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE THEN
  64. ;
  65. ;****************************************************************************************
  66. ;* 
  67. ;*   GetFileTypesThatAppCanNativelyOpen
  68. ;* 
  69. ;*  This routine returns a list of all FileTypes that an application can open by itself
  70. ;* 
  71. ;*  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  72. ;*             appSignature        signature (creator) of application
  73. ;*             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  74. ;* 
  75. ;*  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  76. ;
  77. ;
  78. ; pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  79. ;
  80.     IF ¬ GENERATINGCFM THEN
  81.         Macro
  82.         _GetFileTypesThatAppCanNativelyOpen
  83.             moveq               #28,D0
  84.             dc.w                $ABFC
  85.         EndM
  86.     ELSE
  87.         IMPORT_CFM_FUNCTION GetFileTypesThatAppCanNativelyOpen
  88.     ENDIF
  89.  
  90. ;
  91. ;****************************************************************************************
  92. ;* 
  93. ;*  ExtendFileTypeList
  94. ;* 
  95. ;*  This routine makes a new list of file types that can be translated into a type in the given list
  96. ;*  Used by StandardFile
  97. ;* 
  98. ;*  Enter:    originalTypeList        pointer to list of file types that can be opened
  99. ;*             numberOriginalTypes        number of file types in orgTypeList
  100. ;*              extendedTypeList        pointer to a buffer to be filled with file types
  101. ;*             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  102. ;* 
  103. ;*  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  104. ;*             numberExtendedTypes        number of file types put in extendedTypeList
  105. ;
  106. ;
  107. ; pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  108. ;
  109.     IF ¬ GENERATINGCFM THEN
  110.         Macro
  111.         _ExtendFileTypeList
  112.             moveq               #9,D0
  113.             dc.w                $ABFC
  114.         EndM
  115.     ELSE
  116.         IMPORT_CFM_FUNCTION ExtendFileTypeList
  117.     ENDIF
  118.  
  119. ;
  120. ;****************************************************************************************
  121. ;* 
  122. ;* 
  123. ;*  This routine checks if a file can be opened by a particular application.
  124. ;*  If so, it returns if it needs to be translated first, and if so then how.
  125. ;*  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  126. ;*  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  127. ;* 
  128. ;*  Enter:    targetDocument        document to check if it can be opened
  129. ;*             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  130. ;*             appSignature        signature (creator) of application to open doc
  131. ;*             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  132. ;*             onlyNative            whether to consider if document can be translated before opening
  133. ;*             howToOpen            pointer to buffer in which to put how the document can be opened
  134. ;*             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  135. ;* 
  136. ;*  Exit:    howToOpen            whether file needs to be translated to be read
  137. ;*             howToTranslate        if file can be translated, buffer filled in with how to translate
  138. ;*             returns                noErr, noPrefAppErr
  139. ;
  140. ;
  141. ; pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  142. ;
  143.     IF ¬ GENERATINGCFM THEN
  144.         Macro
  145.         _CanDocBeOpened
  146.             moveq               #30,D0
  147.             dc.w                $ABFC
  148.         EndM
  149.     ELSE
  150.         IMPORT_CFM_FUNCTION CanDocBeOpened
  151.     ENDIF
  152.  
  153. ;
  154. ;****************************************************************************************
  155. ;* 
  156. ;*  GetFileTranslationPaths
  157. ;* 
  158. ;*  This routine returns a list of all ways a translation can occure to or from a FileType.
  159. ;*  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  160. ;* 
  161. ;*  Enter:    srcDoc            source file or NULL for all matches
  162. ;*             dstDoc            destination FileType or NULL for all matches
  163. ;*             maxResultCount
  164. ;*             resultBuffer
  165. ;*  Exit:    number of paths
  166. ;
  167. ;
  168. ; pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  169. ;
  170.     IF ¬ GENERATINGCFM THEN
  171.         Macro
  172.         _GetFileTranslationPaths
  173.             moveq               #56,D0
  174.             dc.w                $ABFC
  175.         EndM
  176.     ELSE
  177.         IMPORT_CFM_FUNCTION GetFileTranslationPaths
  178.     ENDIF
  179.  
  180. ;
  181. ;****************************************************************************************
  182. ;* 
  183. ;*  GetPathFromTranslationDialog
  184. ;* 
  185. ;*  This routine, with a given document, application, and a passed typelist will display the
  186. ;*  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  187. ;*  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  188. ;*  The routine returns the translation path information.
  189. ;* 
  190. ;*  Enter:    theDocument            FSSpec to document to open
  191. ;*             theApplication        FSSpec to application to open document
  192. ;*             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  193. ;*                                 you would like the documented translated to.  Order most perferred
  194. ;*                                 to least.
  195. ;* 
  196. ;*  Exit:    howToOpen            Translation method needed to open document
  197. ;*             howToTranslate        Translation specification
  198. ;*             returns                Any errors that might occur.
  199. ;
  200. ;
  201. ; pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  202. ;
  203.     IF ¬ GENERATINGCFM THEN
  204.         Macro
  205.         _GetPathFromTranslationDialog
  206.             moveq               #55,D0
  207.             dc.w                $ABFC
  208.         EndM
  209.     ELSE
  210.         IMPORT_CFM_FUNCTION GetPathFromTranslationDialog
  211.     ENDIF
  212.  
  213. ;
  214. ;****************************************************************************************
  215. ;* 
  216. ;*   TranslateFile
  217. ;* 
  218. ;*  This routine reads a file of one format and writes it to another file in another format. 
  219. ;*  The information on how to translated is generated by the routine CanDocBeOpened.
  220. ;*  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  221. ;*  The destination file must not exist.  It is created by this routine.  
  222. ;* 
  223. ;*  Enter:    sourceDocument            input file to translate
  224. ;*             destinationDocument        output file of translation
  225. ;*             howToTranslate            pointer to info on how to translate
  226. ;*  Exit:    returns                    noErr, badTranslationSpecErr 
  227. ;
  228. ;
  229. ; pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  230. ;
  231.     IF ¬ GENERATINGCFM THEN
  232.         Macro
  233.         _TranslateFile
  234.             moveq               #12,D0
  235.             dc.w                $ABFC
  236.         EndM
  237.     ELSE
  238.         IMPORT_CFM_FUNCTION TranslateFile
  239.     ENDIF
  240.  
  241. ;
  242. ;****************************************************************************************
  243. ;* 
  244. ;*   GetDocumentKindString
  245. ;* 
  246. ;*  This routine returns the string the Finder should show for the "kind" of a document
  247. ;*  in the GetInfo window and in the kind column of a list view.  
  248. ;* 
  249. ;*  Enter:    docVRefNum        The volume containing the document
  250. ;*             docType            The catInfo.fdType of the document
  251. ;*             docCreator        The catInfo.fdCreator of the document
  252. ;*             kindString        pointer to where to return the string
  253. ;* 
  254. ;*  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  255. ;*             returns            noErr, or afpItemNoFound if kind could not be determined
  256. ;
  257. ;
  258. ; pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  259. ;
  260.     IF ¬ GENERATINGCFM THEN
  261.         Macro
  262.         _GetDocumentKindString
  263.             moveq               #22,D0
  264.             dc.w                $ABFC
  265.         EndM
  266.     ELSE
  267.         IMPORT_CFM_FUNCTION GetDocumentKindString
  268.     ENDIF
  269.  
  270. ;
  271. ;****************************************************************************************
  272. ;* 
  273. ;*  GetTranslationExtensionName
  274. ;* 
  275. ;*  This routine returns the translation system name from a specified TranslationSpec
  276. ;* 
  277. ;*  Enter:    translationMethod    The translation path to get the translation name from
  278. ;* 
  279. ;*  Exit:    extensionName        The name of the translation system
  280. ;*             returns                Any errors that might occur
  281. ;
  282. ;
  283. ; pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  284. ;
  285.     IF ¬ GENERATINGCFM THEN
  286.         Macro
  287.         _GetTranslationExtensionName
  288.             moveq               #54,D0
  289.             dc.w                $ABFC
  290.         EndM
  291.     ELSE
  292.         IMPORT_CFM_FUNCTION GetTranslationExtensionName
  293.     ENDIF
  294.  
  295. ;
  296. ;****************************************************************************************
  297. ;* 
  298. ;*  GetScrapDataProcPtr
  299. ;* 
  300. ;*  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  301. ;*  get the data to be translated.  The first call TranslateScrap will make to this is to
  302. ;*  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  303. ;*  with a list all the formats that you have available to be translated, and the length of each.
  304. ;*  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  305. ;*  the formats that 'fmts' list said was available.
  306. ;* 
  307. ;*  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  308. ;*             dataH                    Handle in which to put the requested data
  309. ;*             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  310. ;*             
  311. ;*  Exit:    dataH                    Handle is resized and filled with data in requested format
  312. ;
  313. ; typedef GetScrapDataUPP                 GetScrapData
  314.  
  315. ;
  316. ;****************************************************************************************
  317. ;* 
  318. ;*  TranslateScrap
  319. ;* 
  320. ;*  This routine resizes the destination handle and fills it with data of the requested format.
  321. ;*  The data is generated by translated one or more source formats of data supplied by
  322. ;*  the procedure srcDataGetter.  
  323. ;*  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  324. ;*  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  325. ;* 
  326. ;*  Enter:    sourceDataGetter            Pointer to routine that can get src data
  327. ;*             sourceDataGetterRefCon        Extra parameter for dataGetter
  328. ;*             destinationFormat            Format of data desired
  329. ;*             destinationData                Handle in which to store translated data
  330. ;*             
  331. ;*  Exit:    dstData                        Handle is resized and filled with data in requested format
  332. ;
  333. ;
  334. ; pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  335. ;
  336.     IF ¬ GENERATINGCFM THEN
  337.         Macro
  338.         _TranslateScrap
  339.             moveq               #14,D0
  340.             dc.w                $ABFC
  341.         EndM
  342.     ELSE
  343.         IMPORT_CFM_FUNCTION TranslateScrap
  344.     ENDIF
  345.  
  346.     ENDIF
  347.     ENDIF ; __TRANSLATION__ 
  348.  
  349.